There are many different ways to use Newt's Cape:. Two common scenarios are book creation (especially for 1.x) and web browsing (only for 2.x using NIE).
A simplified description of what Newt's Cape does:
To create HTML documents, use a text editor or HTML authoring tool, or download web pages from the internet. To minimize problems with Newt's Cape, we would highly recommend that you check any HTML documents first in a desktop web browser before transferring to the Newton. Also, read our suggestions for naming and organizing a collection of interrelated files.
You can enter/edit short documents directly in Notepad, manually or via Serg Koren's HnewTML or Adam Tow's nHTML; create lists with HTMList. You can also create HTML documents in Personal Media and NewtWorks (on NOS 2.1 MessagePads).
Many new desktop HTML authoring tools are becoming available: Adobe's PageMill, Microsoft's FrontPage, etc. We would be interested in your experience with how the HTML from your authoring tool works with Newt's Cape.
Create your graphics using a standard graphics packages. Generally, keep graphics small; use black&white if you are creating 1.x compatible books or are concerned about storage space. On NOS 2.1 (MP2K and eMate), 4-16 levels of gray are available.
Although in principle, Newt's Cape should be able to handle most HTML, here are some suggestions for best results.
This is automatic. Files have a text/html MIME type, and may have .htm or .html extension.
You can access Inbox entries, i.e., beamed from another user, or emailed, e.g., web pages from the WebMail service, for non-real-time web browsing; or, enter/edit short documents directly in Notepad, manually or via Serg Koren's HnewTML editor. You can also create HTML documents in Personal Media or NewtWorks.
For 2.x, you can send other text files, e.g.,
Content-Type: text/plain Content-Length: 18 Content-Base: http://www.foo.com/user/bar.txt this is some text
If there is no Content-Type, it defaults to text/html; length is implicit (when </HTML> is encountered); base URL defaults to <BASE HREF=... inside the document. If there is a Content-Type, it must correspond to an existing helper app; there must also be a Content-Length (length of the content itself, including cr and/or lf chars); Content-Base is optional (and provides a URL or filename that the helperApp might use). Blank line separates header from content.
Specify a direct URL for a .gif file, or use Load with Images for a document that should contain graphics, animated GIFs. Graphics are converted and cached, then displayed as/within documents.
Use Newt's Cape Graphic Converter (NCGC) (available to registered users) on Macintosh or Windows to convert GIF, PICT, BMP files to a text PICT format for Sloup. (Or, the more fearless can copy ICON and PICT resources as hex text via ResEdit). Then, use Sloup, a serial or ADSP connection, and a desktop terminal emulator to transfer the graphics into resource soups on the Newton. Your HTML document can access a graphic with a URL of the form: "soupName/graphicName".
You can also use (animated) graphics that are in the Newton ROM, e.g.,
and
.
There is currently no automatic conversion of internet sound formats. See helper apps.
You can also use sounds that are in the Newton ROM, e.g., beep.
You can download a package to the Newton if the URL ends with .pkg, and its MIME type matches current (evolving) package conventions (preferably "application/x-newton-compatible-pkg"; however, several other types will work (if not, you can customize via helppkgi.htm example). After downloading, you can confirm if you want to replace and/or install it immediately, or add to Inbox for later. The prompt displays new (& old) version number and creation date.
Although there are no size limits imposed by HTML, even in desktop web browsers, it usually practical and preferable to have information segmented into "pages" so that a user can look at useful content and context without having to wait a long time.
From a user access/navigation perspective, neither very l-o-n-g files nor single paragraphs are desirable as documents.
On the Newton, it is possible to create very large books from a single HTML file on 2.x (or, if you do not need to display it immediately via Process:Save Package). Still, heap is a major limitation on most Newtons. A practical limit to build and browse a single HTML source in Newt's Cape 1.5 is ~15-20K of text on 1.x -- somewhat larger on 2.x, or if you don't want to save it as a package, and text has minimal markup.
You can use LINK to combine multiple Notes and/or saved books ("chapters"). If you want to have many smaller books (one per HTML document) on NOS 1.x, you will definitely need some kind of Extras/archive manager like NewtCase or ScrollEx.
Mark Heringer holds the current Newt's Cape record for largest book (created on MP130): Indian Heroes and Great Chieftains is ~397 Landscape pages, 526K !
Although Newt's Cape wraps wide headings, splits long paragraphs, and scales tables, you may want to shorten and segment individual text items yourself to improve readability if you are creating HTML documents primarily for a smaller (Newton) screen. Somewhat smaller objects are also advantageous from the processing perspective: a lengthy, multi-page P or PRE object might exhaust Newton heap. (At the other extreme, many one-line objects can also rapidly deplete heap due to object overhead).
Since Newt's Cape currently uses Newton books as a container for HTML documents, in order to reference (link to) other books on the Newton using a unique ISBN, you are limited to 14 characters. To maximize portability of HTML documents to other systems and browsers, we suggest using an 8.3 filename, e.g., testdoc1.htm, either all lowercase or all UPPERCASE for consistency. (If you don't care about DOS, then 9.4 is fine).
The current Newton does not have a mechanism such as file directories for
organizing packages (actually, you could move books to different folders in
Extras), so there is only minor support for
"pathnames" currently. BASE
is used to interpret relative pathnames for links. For graphics objects,
use one level of "directory" to refer to a soup (local
objectbase), with the "filename" referring to an object stored
in a name slot within the soup. Of course, external http: URL
references can be fully specified.
If you are attempting to create a collection of books on the Newton, you should adopt a few simple conventions for creating a collection of interrelated documents and graphics files that will work on both the desktop and Newton. (This section can be skipped if you are web browsing and not saving books for later offline use).
For example, this series of documents resides in the same directory on a desktop computer. You can access documents in subdirectories, but since Newt's Cape ignores directory paths for saved books, the filenames should be unique.
Any graphics are stored as .gif in a subdirectory; in the same directory are Sloup files -- the soup (on the first line), e.g., picts corresponds to the name of the subdirectory, and the name for the PICT object, e.g., foo.gif corresponds to the name of the original file. You can use any directories/soups that you choose, but by convention, we typically put bitmap objects in "bitmaps" and PICTs in the "picts" soup. As mentioned earlier, keeping filenames short (8.3) increases cross-platform portability. Advanced NewtonScript techniques for shadowing URLs
This document (in all its formats) is © 1995-98. Steve Weyer, Greg Simon. All Rights Reserved Worldwide
Version 1.5. Last updated: Jan 1998